.TH "PLP_SNPRINTF" 3 "Dec 12, 1998" V98.12.13
.SH NAME
plp_snprintf, plp_vsnprintf - formatted output conversion
.SH SYNOPSIS
.br
#include <stdarg.h>
.br
void plp_snprintf(char *str, int size, const char *format, ...);
.br
void plp_vsnprintf(char *str, int size, const char *format, va_list ap);
.br
extern int visible_control;
.br
.SH "HISTORY, TERMS AND CONDITIONS"
.IX "plp_snprintf" "" "format and print C language values"
.LP
This version of plp_snprintf was developed originally for printing on a motley
collection of specialized hardware that had NO IO library.
Due to contractual
restrictions,  a clean room implementation of the printf() code had to be
developed.
.LP
The implementation of plp_snprintf tends to be overly paranoid,
as these platforms had NO memory protection,  and very small address spaces.
This made it possible to try to print very long strings, i.e. - all of memory,
very easily.
To guard against this,  all printing was done via a fixed size buffer,
generous enough to hold reasonable strings,  but small enough to protect against
overruns, etc.
.LP
Strangely enough,  this proves to be of immense importance when SPRINTFing to
a buffer on a stack.
The rest,  of course,  is well known,  as buffer overruns
in the stack are a common way to do horrible things to operating systems,
security, etc etc.
.LP
This version of the plp_snprintf documentation is based on the
snprintf() manual page from BSDI Inc,
the POSIX printf() documention, and the 4.4 BSD Release printf() manual page.
.LP
The plp_snprintf() source code is freely distributible under the following
license terms:
.LP
You may use, copy, distribute, or otherwise incorporate this software and documentation
into any product or other item,  provided that the copyright in the documentation and source code
as well as the source code generated
constant strings in the object, executable or other code remain in place and are present
in executable modules or objects.
.LP
You may modify this
code as appropriate to your usage; however the modified version must be identified by changing
the various source and object code identification strings as is appropriately
noted in the source code.
.LP
.SH DESCRIPTION
.LP
The plp_snprintf() and plp_vsnprintf() procedures write to a string under
the control of a format string that specifies how subsequent arguments
output.
.LP
The plp_snprintf() and plp_vsnprintf() will write at most size-1
characters floowed by a `\0'.
If str is 0 (NULL) or size is 0, then no characters are written.
.LP
The visible_control variable (default value 1) is used when printing character
or string values.  If the character C to be printed is a control character
or and not a space as determined by the ctype.h library iscntrl()
and isspace() functions,  then it will be printed as the form ^X,
where X = (C & 0x1f) | '@' in C language notation.
.LP
The format string is composed of zero or more directives:
ordinary characters (not %), which are copied unchanged to the output stream;
and conversion specifications, each of which results in fetching zero or more
subsequent arguments.
Each conversion specification is introduced by the
character %. The arguments must correspond properly (after type promotion) with the conversion specifier.
After the %, the following appear
in sequence:
.IP o
Zero or more of the following flags:
.LP
.IP -
A zero `0' character specifying zero padding.
For all conversions except n, the converted value is padded on the left with
zeros rather than blanks.
If a precision is given with a numeric
conversion (d, i, o, u, i, x, and X), the `0' flag is ignored.
.LP
.IP -
A negative field width flag `-' indicates the converted value is
to be left adjusted on the field boundary.
.LP
.IP -
A `+' character specifying that a sign always be placed before a
number produced by a signed conversion.
.LP
.IP o
An optional decimal digit string specifying a minimum field width.
If the converted value has fewer characters than the field width, it
will be padded with spaces on the left
(or right, if the left-adjustment flag has been given) to fill out the field width.
Note that e, f, and g formats are restricted to a maximum of 64 characters.
.LP
.IP o
An optional precision, in the form of a period `.' followed by an optional digit string.
If the digit string is omitted, the precision
is taken as zero.
This gives the minimum number of digits to appear
for d, i, o, u, x, and X conversions, the number of digits to appear
after the decimal-point.
For e, f, and g conversions, the meaning depends on the local system sprintf() support.
.LP
.IP o
The optional character l (ell) specifying that a following d, i, o,
u, x, or X conversion applies to a long int or unsigned
long int argument.
.LP
.IP o
The optional character q, specifying that a following d, i, o, u, x,
or X conversion corresponds to a quad or long long.
.LP
.IP o
A character that specifies the type of conversion to be applied.
.LP
A field width or precision, or both, may be indicated by an asterisk `*'
instead of a digit string.
In this case, an int argument supplies the
field width or precision.
A negative or zero field width is ignored.
.LP
The conversion specifiers and their meanings are:
.IP diouxX
The int (or appropriate variant) argument is converted to signed
decimal (d and i), unsigned octal (o), unsigned decimal (u), or
unsigned hexadecimal (x and X) notation.
The letters abcdef are
used for x conversions; the letters ABCDEF are used for X conversions.
The precision, if any, gives the minimum number of digits
that must appear; if the converted value requires fewer digits,
it is padded on the left with blanks unless zero padding has been requested.
.IP efg
The double argument is rounded and converted in the style
of the underlying systems sprintf() support.  Lengths and other critical
values have been check,  and the maximum length of converted value is 64 bytes.
.IP c
The int argument is converted to an unsigned char, and the resulting character is written,
as modified by the visible_control variable value.
.IP s
The ``char *'' argument is expected to be a pointer to an array
of character type (pointer to a string).
Characters from the array are written up to (but not including) a terminating NUL character; if a precision is specified, no more than the number specified are written.
Characters are writen to the string as modified by the visible_control variable value.
.IP %
A `%' is written. No argument is converted. The complete conversion specification is `%%'.
.LP
In no case does a non-existent or small field width cause truncation of a
field; if the result of a conversion is wider than the field width, the
field is expanded to contain the conversion result.
.LP
SH BUGS
.lp
The typedef names quad_t and u_quad_t are ugly, ugly, ugly.
Your system may use different quad type names.
.LP
.SH COPYRIGHT
.LP
The source code and documentation is Copyright 1988-1999 by Patrick Powell
<papowell@astart.com>.
